<!-------- @HEADER
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 !  Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
 !                  Copyright 2012 Sandia Corporation
 !
 ! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
 ! the U.S. Government retains certain rights in this software.
 !
 ! Redistribution and use in source and binary forms, with or without
 ! modification, are permitted provided that the following conditions are
 ! met:
 !
 ! 1. Redistributions of source code must retain the above copyright
 ! notice, this list of conditions and the following disclaimer.
 !
 ! 2. Redistributions in binary form must reproduce the above copyright
 ! notice, this list of conditions and the following disclaimer in the
 ! documentation and/or other materials provided with the distribution.
 !
 ! 3. Neither the name of the Corporation nor the names of the
 ! contributors may be used to endorse or promote products derived from
 ! this software without specific prior written permission.
 !
 ! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
 ! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 ! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
 ! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 ! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 ! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 ! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 ! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 ! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 ! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 !
 ! Questions? Contact Karen Devine	kddevin@sandia.gov
 !                    Erik Boman	egboman@sandia.gov
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 ! @HEADER
-------> 
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.76 [en] (X11; U; Linux 2.4.2-2smp i686) [Netscape]">
   <meta name="sandia.approved" content="SAND99-1376">
   <meta name="author" content="karen devine, kddevin@sandia.gov">
   <title> Zoltan Developer's Guide:  Timing Routines</title>
</head>
<body bgcolor="#FFFFFF">

<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_services_zoltantimer.html">Next</a>&nbsp; |&nbsp; <a href="dev_services_hash.html">Previous</a></i></b></div>
<!------------------------------------------------------------------------->
<h2>
<a NAME="Timing"></a>Timing Routines</h2>
To assist in performance measurements and profiling, several timing routines
are included in the Zoltan library. The main timer function, 
<b><a href="#Zoltan_Time">Zoltan_Time</a></b>,
provides access to at least two portable timers: one CPU clock and one
wall clock. On most systems, user time can also be measured.
A higher-level timing capability built using 
<b><a href="#Zoltan_Time">Zoltan_Time</a></b> is also available; see
<b><a href="dev_services_zoltantimer.html">ZOLTAN_TIMER</a></b> for more 
details.
<p>
The routines included in the utility are listed below.
<blockquote><b><a href="#Zoltan_Time">Zoltan_Time</a></b>: Returns the
time (in seconds) after some fixed reference point in time.
<br><b><a href="#Zoltan_Time_Resolution">Zoltan_Time_Resolution</a></b>:&nbsp;
The resolution of the specified timer.</blockquote>
Currently, the following timers are supported:
<ul>
<li>
<i>ZOLTAN_TIME_WALL </i>: wall-clock time.</li>

<br>On most systems, this timer calls MPI_Wtime.
<li>
<i>ZOLTAN_TIME_CPU </i>: cpu time.</li>

<br>On most systems, this timer calls the ANSI C function clock(). Note
that this timer may roll over at just 71 minutes. <b><a href="#Zoltan_Time">Zoltan_Time</a></b>
attempts to keep track of the number of roll-overs but this feature will
work only if <b><a href="#Zoltan_Time">Zoltan_Time</a></b> is called at
least once during every period between roll-overs.
<li>
<i>ZOLTAN_TIME_USER </i>: user time.</li>

<br>On most systems, this timer calls times(). Note that times() is required
by POSIX and is widely available, but it is not required by ANSI C so may
be unavailable on some systems. Compile Zoltan with -DNO_TIMES in this
case.</ul>
Within Zoltan, it is recommended to select which timer to use by setting
the
<a href="../ug_html/ug_param.html#TIMER">TIMER</a> general parameter
via <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
The default value of <a href="../ug_html/ug_param.html#TIMER">TIMER</a>
is <i>wall</i>.&nbsp; Zoltan stores an integer representation of the selected
timing method in <i>zz->Timer</i>. This value should be passed to <b><a href="#Zoltan_Time">Zoltan_Time</a></b>,
as in <b><a href="#Zoltan_Time">Zoltan_Time</a></b>(<i>zz->Timer</i>).
<p><!------------------------------------------------------------------------->
<hr><a NAME="Zoltan_Time"></a>
<hr>double <b>Zoltan_Time</b>(int <i>timer</i>);&nbsp;
<hr>
<p><b>Zoltan_Time</b> returns the time in seconds, measured from some fixed
reference time. Note that the time is <i>not </i>synchronized among different
processors or processes. The time may be either CPU time or wall-clock
time. The timer is selected through <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>.
<br>&nbsp;
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>timer</i></td>

<td>The timer type (e.g., wall or cpu) represented as an integer. See <a href="#Timing">top
of page</a> for a list of valid values.</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; double&nbsp;</td>

<td>The time in seconds. The time is always positive; a negative value
indicates an error.</td>
</tr>
</table>

<p><!------------------------------------------------------------------------->
<hr><a NAME="Zoltan_Time_Resolution"></a>
<hr>double <b>Zoltan_Time_Resolution</b>(int
<i>timer</i>) ;&nbsp;
<hr>
<br><b>Zoltan_Time_Resolution</b> returns the resolution of the current
timer.&nbsp; The returned resolution is a lower bound on the actual resolution.
<br>&nbsp;
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; <i>timer</i></td>

<td>The timer type (e.g., wall or cpu) represented as an integer. See <a href="#Timing">top
of page</a> for a list of valid values.</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; double&nbsp;</td>

<td>The timer resolution in seconds.&nbsp; If the resolution is unknown,
-1 is returned.</td>
</tr>
</table>

<br>&nbsp;
<p><!------------------------------------------------------------------------->
<hr><a NAME="Example"></a>
<br><b>Example:</b>
<br>Here is a simple example for how to use the timer routines:
<ul><tt>double t0, t1, t2;</tt>
<br><tt>Zoltan_Set_Param(zz, "TIMER", "wall");</tt>
<br><tt>t0 = Zoltan_Time(zz->Timer);</tt>
<br><tt>/* code segment 1&nbsp; */</tt>
<br><tt>t1 = Zoltan_Time(zz->Timer);</tt>
<br><tt>/* code segment 2&nbsp; */</tt>
<br><tt>t2 = Zoltan_Time(zz->Timer);</tt>
<br><tt>/* Print timing results */</tt>
<br><tt>Zoltan_Print_Stats(zz->Communicator, zz->Debug_Proc, t1-t0, "Time
for part 1:");</tt>
<br><tt>Zoltan_Print_Stats(zz->Communicator, zz->Debug_Proc, t2-t1, "Time
for part 2:");</tt>
<br><tt>Zoltan_Print_Stats(zz->Communicator, zz->Debug_Proc, t2-t0, "Total
time :");</tt></ul>

<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_services_debug.html">Next:&nbsp;
Debugging Services</a> |&nbsp; <a href="dev_services_hash.html">Previous:&nbsp;
Hash Function</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>
